// Copyright 2012 Jay Young. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS-IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * @fileoverview
 *
 * References describing the data structures used by DocInfo objects.  This file
 * is not executable code, but merely a set of schema definitions.
 */


/**
 * The Descriptor structure used to hold fileoverview, author, and see
 * references.
 */
var FileDescriptor = {
  // The @fileoverview text.
  fileOverview: '',

  // @authors
  authors: [''],

  // @see
  references: ['']
};


/**
 * The Descriptor structure used for classes and interfaces.
 */
var ClassDescriptor = {
  name: '',
  
  // The visibility of the class
  visibility: JSDocInfo.Visibility,

  // The descriptive text included with the constructor function.
  classDoc: '',

  // An array containing any "@see" tag references
  references: undefined || [''],

  // If a class is deprecated, this value will be a string containing the
  // text of the @deprecation tag.  Otherwise, this will be undefined.
  deprecationReason: undefined || '',

  // Constructor parameters.
  params: [{
    // The parameter name
    name: '',

    // The parameter type
    type: '',

    // The descriptive text included with the parameter.
    desc: ''
  }],

  properties: {
    // Each property name maps to an object
    name: PropertyDescriptor
  },
  
  methods: {
    name: FunctionDescriptor
  },

  // Only for classes
  baseType: '',
  interfaces: [''],

  // Only for interfaces
  extendedInterfaces: [''],
  
  // Static properties - a map of names to either function or property
  // descriptors
  statics: {
    name: (FunctionDescriptor || PropertyDescriptor)
  }
};


/**
 * The Descriptor structure used for functions (both methods and library
 * functions).
 */
var FunctionDescriptor = {
  desc: '',

  // Whether @override or @inheritDoc are present on the method
  isOverride: true,

  // Visibility of the method.
  visibility: DocInfo.Vis,
  
  deprecationReason: '',

  // If this function is a class property to which "goog.abstractMethod" is
  // assigned.
  isAbstractMethod: true,

  // Parameter list
  params: [{
    // The parameter name
    name: '',

    // The parameter type
    type: JSTypeExpression,

    // The descriptive text included with the parameter.
    desc: ''
  }],

  // Return descriptor
  returns: {
    type: JSTypeExpression,
    desc: ''
  }
};


/**
 * The descriptor structure used for class, interface, and global properties.
 */
var PropertyDescriptor = {
  // Even though properties are mapped by name, also include the name in
  // the property descriptor.
  name: '',

  // The type expression delcared in the property's JSDoc comment, if any.
  type: '',

  // The description, if any.
  desc: '',

  // The visibility, either expressly declared or inferred.
  visibility: DocInfo.Vis
};


/**
 * The Descriptor structure used for enum objects.
 */
var EnumDescriptor = {
  enumDoc: '',

  // The enum type
  type: JSTypeExpression,

  // An array containing any "@see" tag references
  references: undefined || [''],

  // If an enum is deprecated, this value will be a string containing the
  // text of the @deprecation tag.  Otherwise, this will be undefined.
  deprecatedReason: undefined || '',

  // The enum's key/value pairs.  The Enum documenter understands string,
  // number, null, undefined, and goog.events.getUniqueId()'ed values.
  map: {
    key: {
      doc: '',
      value: ''
    }
  }
};


/**
 * Descriptor structure used for documenting @typedefs.
 */
var TypedefDescriptor = {
  typedefDoc: '',

  // The type being given a name
  type: JSTypeExpression,
  
  // If a typedef is deprecated, this value will be a string containing the
  // text of the @deprecation tag.  Otherwise, this will be undefined.
  deprecationReason: undefined || '',
  
  // An array containing any "@see" tag references
  references: undefined || ['']
};
